---
displayed_sidebar: "Chinese"
---

# json_keys

## 功能

返回 JSON 对象中所有最上层成员 (key) 组成的数组。如果指定了`path`，则返回与`path`匹配的最上层成员组成的数组。

## 语法

```SQL
json_keys(json_doc[, path])
```

## 参数说明

- `json_doc`： JSON 字符串，必选。必须为 JSON 对象 (object)。

- `path`：路径表达式，可选。取值类型为 VARCHAR。`path` 一般以 `$` 符号作为开头；使用 `.` 作为路径分隔符；使用 `[]` 表示数组下标， 从 0 开始。

## 返回值说明

返回 JSON ARRAY 类型的值。

如果输入的 JSON 对象为空，则返回空数组。

如果`json_doc`不是 JSON 对象或者指定的路径不存在，则返回 `NULL`。

如果`json_doc`为包含 JSON 对象的数组，可以使用`path`指向该对象，正常返回值，见示例五。

## 示例

示例一: JSON 对象为空对象，返回空数组。

```Plain
SELECT JSON_KEYS('{}');
+-----------------+
| json_keys('{}') |
+-----------------+
| []              |
+-----------------+
```

示例二: 返回 JSON 对象的所有最上层 key 组成的数组。

```Plain
SELECT JSON_KEYS('{"a": 1, "b": 2, "c": 3}');
+---------------------------------------+
| json_keys('{"a": 1, "b": 2, "c": 3}') |
+---------------------------------------+
| ["a", "b", "c"]                       |
+---------------------------------------+
```

示例三：返回指定路径下所有最上层 key 组成的数组。

```Plain
SELECT JSON_KEYS('{"a": 1, "b": 2, "c": {"d": 3, "e": 4, "f": 5}}', '$.c');
+---------------------------------------------------------------------+
| json_keys('{"a": 1, "b": 2, "c": {"d": 3, "e": 4, "f": 5}}', '$.c') |
+---------------------------------------------------------------------+
| ["d", "e", "f"]                                                     |
+---------------------------------------------------------------------+
```

示例四：指定的路径不存在，返回 NULL。

```JSON
SELECT JSON_KEYS('{"a": 1, "b": 2, "c": {"d": 3, "e": 4, "f": 5}}', '$.e');
+---------------------------------------------------------------------+
| json_keys('{"a": 1, "b": 2, "c": {"d": 3, "e": 4, "f": 5}}', '$.e') |
+---------------------------------------------------------------------+
| NULL                                                                |
+---------------------------------------------------------------------+
```

示例五：输入的字符串非 JSON 对象，且未指定`path`，返回 NULL。

```JSON
SELECT JSON_KEYS('[1, 2, {"a": 1, "b": 2}]');
+---------------------------------------+
| json_keys('[1, 2, {"a": 1, "b": 2}]') |
+---------------------------------------+
| NULL                                  |
+---------------------------------------+
```

示例六：输入的字符串为包含 JSON 对象的数组，且 JSON 对象与路径匹配，正常返回值。

```JSON
SELECT JSON_KEYS('[0, 1, {"a": 1, "b": 2}]', '$[2]');
+-----------------------------------------------+
| json_keys('[0, 1, {"a": 1, "b": 2}]', '$[2]') |
+-----------------------------------------------+
| ["a", "b"]                                    |
+-----------------------------------------------+
```
